The last version of this book and other documents are available at the URL
http://book.duckietown.org/
C0C0C0rvizDuckietown is a robotics educations and outreach effort.
The most tangible goal of the project is to provide a low-cost educational platform for learning autonomy, consisting of the Duckiebots, an autonomous robot, and the Duckietowns, the infrastructure in which the Duckiebots navigates.
However, we focus on the learning experience as a whole, by providing a set of modules teaching plans and other guides, as well as a curated role-play experience.
We have two targets:
In addition, the Duckietown platform has been used as a research platform.
While we are at the early phases of the project, many people have been used the materials in the past year.
The best way to get a sense of how the platform looks is to watch these videos. They show off the capabilities of the platform.
add 4 “cool” videos currently in the home page
This video is part of the Red Hat documentary:
add Red Hat video
These papers present a more formal description of the technical side of the projecrt as well as the educational side.
This paper [1] describes the course design for Duckietown: learning objectives, teaching methods, etc.
This video is a Duckumentary about the first version of the class, during Spring 2016. The Duckumentary was shot by Chris Welch.
Duckumentary about the release.
The paper [2] describes the Duckiebot and its software. With 29 authors, we made the record for a robotics conference.
Liam
Duckietown started as an MIT class during Spring 2016.
In 2017, the class will be offered contemporaneously at:
as well as:
If you are an instructor, please jump to Section 3.2.
If you are a self-guided learner, please jump to Section 3.3.
If you are a company, and interested in working with Duckietown, please jump to Section 3.4.
to write
to write
to write
add link to Facebook
add link to Mailing list
add link to Slack?
If you want to contribute to the software…
If you want to contribute to the hardware…
If you want to contribute to the documentation…
If you want to contribute to the dissemination…
What is Duckietown?
Duckietown is a low-cost educational and research platform.
Is Duckietown free to use?
Yes. All materials are released according to an open source license.
Is everything ready?
Not quite! Please sign up to our mailing list to get notified when things are a bit more ready.
How can I start?
See the next section, Getting started.
How can I help?
If you would like to help actively, please email duckietown@mit.edu.
I want to build my own Duckiebot. How do I get started?
to write
How large a class can it be? I teach large classes.
to write
What is the budget for the robot?
to write
I want to teach a Duckietown class. How do I get started?
Please get in touch with us at duckietown@mit.edu. We will be happy to get you started and sign you up to the Duckietown instructors mailing list.
Why the duckies?
Compared to other educational robotics projects, the presence of the duckies is what makes this project stand out. Why the duckies?
We want to present robotics in an accessible and friendly way.
copy usual discussion from somewhere else.
add picture of kids with Duckiebots.
Currently, Duckietown has the following accounts:
duckietown-teaching mailing list, for low-rate communication with instructors;If you are an international contributor:
All the documentation is in the repository duckietown/duckuments.
The documentation is written as a series of small files in Markdown format.
It is then processed by a series of scripts to create this output:
The simplest way to contribute to the documentation is to click any of the “✎” icons next to the headers.
They link to the “edit” page in Github. There, one can make and commit the edits in only a few seconds.
In the multiple-page version, each page also includes a comment box powered by a service called Disqus. This provides a way for people to write comments with a very low barrier. (We would periodically remove the comments.)
In the following, we are going to assume that the documentation system is
installed in ~/duckuments. However, it can be installed anywhere.
We are also going to assume that you have setup a Github account with working public keys.
On Ubuntu 16.04, these are the dependencies to install:
$ sudo apt install libxml2-dev libxslt1-dev
$ sudo apt install libffi6 libffi-dev
$ sudo apt install python-dev python-numpy python-matplotlib
$ sudo apt install virtualenv
duckuments repoDownload the duckietown/duckuments repository in that directory:
$ git clone git@github.com:duckietown/duckuments ~/duckuments
Next, we will create a virtual environment using inside the ~/duckuments
directory.
Change into that directory:
$ cd ~/duckuments
Create the virtual environment using virtualenv:
$ virtualenv --system-site-packages deploy
Other distributions: In other distributions you might need to use venv instead of virtualenv.
Activate the virtual environment:
$ source ~/duckuments/deploy/bin/activate
mcdp external repositoryMake sure you are in the directory:
$ cd ~/duckuments
Clone the mcdp external repository, with the branch duckuments.
$ git clone -b duckuments git@github.com:AndreaCensi/mcdp
Install it and its dependencies:
$ cd ~/duckuments/mcdp
$ python setup.py develop
If you get a permission error here, it means you have not properly activated the virtual environment.
Other distributions: If you are not on Ubuntu 16, depending on your system, you might need to install these other dependencies:
$ pip install numpy matplotlib
Make sure you have deployed and activated the virtual environment. You can check
this by checking which python is active:
$ which python
/home/![user]/duckuments/deploy/bin/python
Then:
$ cd ~/duckuments
$ make duckuments-dist
This creates the directory duckuments-dist, which contains
another checked out copy of the repository, but with the branch gh-pages, which
is the branch that is published by Github using the “Github Pages” mechanism.
At this point, please make sure that you have these two .git folders:
~/duckuments/.git
~/duckuments/duckuments-dist/.git
To compile the docs, run make clean compile:
$ make clean compile
To see the result, open the file
./duckuments-dist/master/duckiebook/index.html
If you want to do incremental compilation, you can omit the clean and just
use:
$ make compile
This will be faster. However, sometimes it might get confused. At that point,
do make clean.
This is the workflow:
master branch of the duckuments repository.make compile to make sure it compiles.master branch.Done. A bot will redo the compilation and push the changes in the gh-pages branch.
Step 2 is there so you know that the bot will not encounter errors.
This part is now done by a bot, so you don’t need to do it manually.
To deploy the documentation, jump into the DUCKUMENTS/duckuments-dist directory.
Run the command git branch. If the out does not say that you are on the branch gh-pages,
then one of the steps before was done incorrectly.
$ cd $DUCKUMENTS/duckuments-dist
$ git branch
...
* gh-pages
...
Now, after triple checking that you are in the gh-pages branch, you can
use git status to see the files that were added or modified,
and simply use git add, git commit and git push to push the files
to Github.
The dependencies below are harder to install. If you don’t manage
to do it, then you only lose the ability to compile the PDF. You can do make compile
to compile the HTML version, but you cannot do make compile-pdf.
nodejsEnsure the latest version (>6) of nodejs is installed.
Run:
$ nodejs --version
6.xx
If the version is 4 or less, remove nodejs:
$ sudo apt remove nodejs
Install nodejs using the instructions at this page.
Next, install the necessary Javascript libraries using npm:
$ cd $DUCKUMENTS
$ npm install MathJax-node jsdom@9.3 less
nodejs installation problemsThe only pain point in the installation procedure has been the installation of nodejs packages using npm. For some reason, they cannot be installed globally (npm install -g).
Do not use sudo for installation. It will cause problems.
If you use sudo, you probably have to delete a bunch of directories,
such as: RBROOT/node_modules, ~/.npm, and ~/.node_modules, if they exist.
Install PrinceXML from this page.
Download STIX fonts from this site.
Unzip and copy the ttf to ~/.fonts:
$ cp -R STIXv2.0.0 ~/.fonts
and then rebuild the font cache using:
$ fc-cache -fv
To compile the PDF, use:
$ make compile-pdf
This creates the file:
./duckuments-dist/master/duckiebook.pdf
The Duckiebook is written in a Markdown dialect. A subset of LaTeX is supported.
There are also some additional features that make it possible to create publication-worthy materials.
You can use $\LaTeX$ math, environment, and references. For example, take a look at
$$ x^2 = \int_0^t f(\tau)\ \text{d}\tau $$
or refer to Proposition 1.
Proposition example This is an example proposition: $2x = x + x$.
The above was written as in Figure 1.
You can use $\LaTeX$ math, environment, and references.
For example, take a look at
\[
x^2 = \int_0^t f(\tau)\ \text{d}\tau
\]
or refer to [](#prop:example).
\begin{proposition}[Proposition example]\label{prop:example}
This is an example proposition: $2x = x + x$.
\end{proposition}
other LaTeX features supported
Use the syntax “![name]” for describing the variables in the code.
For example, to obtain:
$ ssh ![robot name].local
Use the following:
For example, to obtain:
$ ssh ![robot name].local
Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the LaTeX interpreter.
Use the string
to write the dollar symbol $
, otherwise it
gets confused with LaTeX math materials. Also notice that you should probably
use “USD” to refer to U.S. dollars.$
Other symbols to escape are shown in Table 1.
use $ |
instead of $ |
use ` |
instead of ` |
use &#lt; |
instead of < |
use &#gt; |
instead of > |
Use the kbd element for keystrokes.
For example, to obtain:
Press a then Ctrl-C.
use the following:
Press <kbd>a</kbd> then <kbd>Ctrl</kbd>-<kbd>C</kbd>.
For any element, adding an attribute called figure-id
with value fig:![figure ID] or tab:![table ID]
will create a figure that wraps the element.
For example:
<div figure-id="fig:![figure ID]">
![figure content]
</div>
It will create HMTL of the form:
<div id='fig:code-wrap' class='generated-figure-wrap'>
<figure id='fig:![figure ID]' class='generated-figure'>
<div>
![figure content]
</div>
</figure>
</div>
To add a caption, add an attribute figure-caption:
<div figure-id="fig:![figure ID]" figure-caption="This is my caption">
![figure content]
</div>
Alternatively, you can put anywhere an element figcaption with ID ![figure id]:caption:
<element figure-id="fig:![figure ID]">
![figure content]
</element>
<figcaption id='fig:![figure ID]:caption'>
This the caption figure.
</figcaption>
To refer to the figure, use an empty link:
Please see [](#fig:![figure ID]).
The code will put a reference to “Figure XX”.
The shortcuts col2, col3, col4, col5
are expanded in tables with 2, 3, 4 or 5 columns.
The following code:
<col2 figure-id="tab:mytable" figure-caption="My table">
<span>A</span>
<span>B</span>
<span>C</span>
<span>D</span>
</col2>
gives the following result:
| A | B |
| C | D |
“Invalid XML”
“Markdown” doesn’t mean that you can put anything in a file. Except for the code blocks, it must be valid XML. For example, if you use “>” and “<” without quoting, it will likely cause a compile error.
“Tabs are evil”
Do not use tab characters. The error message in this case is quite helpful in telling you exactly where the tabs are.
The error message contains ValueError: Suspicious math fragment '$\LaTeX$'
You probably have forgotten to indent a command line by at least 4 spaces. The dollar in the command line is now being confused for a math formula.
This chapter describes the conventions for writing the technical documentation.
The following holds for all technical writing.
The documentation is written in correct English.
Do not say “should” when you mean “must”. “Must” and “should” have precise meanings and they are not interchangeable. These meanings are explained in this document.
“Please” is unnecessary in technical documentation.
“Please remove the SD card.”
“Remove the SD card”.
“The pwd is
ubuntu.”“The password is
ubuntu.”
Do not use emojis.
Do not use ALL CAPS.
Make infrequent use of bold statements.
Do not use exclamation points.
It’s ok to use “it’s” instead of “it is”, “can’t” instead of “cannot”, etc.
All the filenames and commands must be enclosed in code blocks using Markdown backticks.
“Edit the ~/.ssh/config file using vi.”
“Edit the
~/.ssh/configfile usingvi.”
ssh etc. are not verbs.“Ctrl-C from the command line”.
“Use Ctrl-C from the command line”.
Use either “laptop” or “duckiebot” (not capitalized, as a hostname) as the prefix for the command line.
For example, for a command that is supposed to run on the laptop, use:
laptop $ cd ~/duckietown
It will become:
laptop $ cd ~/duckietown
For a command that must run on the Duckiebot, use:
duckiebot $ cd ~/duckietown
It will become:
duckiebot $ cd ~/duckietown
If the command is supposed to be run on both, omit the hostname:
$ cd ~/duckietown
“Duckiebot” is always capitalized.
Use “Raspberry Pi”, not “PI”, “raspi”, etc.
These are other words frequently misspelled:
5 GHz WiFi
When the user must edit a file, just say: “edit /this/file”.
Writing down the command line for editing, like the following:
$ vi /this/file
is too much detail.
(If people need to be told how to edit a file, Duckietown is too advanced for them.)
Write the documentation as if every step succeeds.
Then, at the end, make a “Troubleshooting” section.
Organize the troubleshooting section as a list of symptom/resolution.
The following is an example of a troubleshooting section.
This strange thing happens.
Maybe the camera is not inserted correctly. Remove and reconnect.
This other strange thing happens.
Maybe the plumbus is not working correctly. Try reformatting the plumbus.
Atom An atom is a concrete resource (text, video) that is the smallest unit that is individually addressable. It is indivisible.
Examples of atoms include:
Atoms form a directed graph, called “semantic graph”.
Each node is an atom.
The graph has four different types of edges:
A “module” is an abstraction from the point of view of the teacher.
Module A module is a directed graph, where the nodes are either atoms or other modules, and the edges can be of the four types described in Subsection 9.1.2.
Because modules can contain other modules, they allow to describe hierarchical contents. For example, a class module is a module that contains other modules; a “degree” is a module that contains “class” modules, etc.
Modules can overlap. For example, a “Basic Object Detection” and an “Advanced Object Detection” module might have a few atoms in common.
Each atom has the following properties:
- and ‘_’). The ID is used for cross-referencing.
It is the same in all languages.text, setup, demo, exercise.There might be different versions of each atom. This is used primarily for dealing with translations of texts, different representations of the same image, Powerpoint vs Keynote, etc.
A version is a tuple of attributes.
The attributes are:
Language: A language code, such as en-US (default), zh-CN, etc.
Mime type: a MIME type.
Each atom version has:
draft, ready.For the text-like resources, they are described in Markdown files.
The name of the file does not matter.
All files are encoded in UTF-8.
Each file starts with a H1 header. The contents is the title.
The header has the following attributes:
{#ID})lang ({lang=en-US}).type ({type=demo}).status ({status=draft}).Here is an example of a header with all the attributes:
# Odometry calibration {#odometry-calibration lang=en-US type=demo status=ready}
This first paragraph will be used as the "summary" for this text.
calibration.en.mdAnd this is how the Italian translation would look like:
# Calibrazione dell'odometria {#odometry-calibration lang=it type=demo status=draft}
Questo paragrafo sarà usato come un sommario del testo.
calibration.it.mdIn the text, you describe the semantic graph using tags and IDs.
In Markdown, you can give IDs to sections using the syntax:
# Setup step 1 {#setup-step1}
This is the first setup step.
Then, when you write the second step, you can add a a semantic edge using the following.
# Setup step 2 {#setup-step2}
This is the second setup step.
Requires: You have completed the first step in [](#setup-step1).
The following table describes the syntax for the different types of semantic links:
| Requires | |
| Recommended | |
| Reference | |
| See also | |
Define a micro-format for this.
Define here all the configurations that we use.
Configuration D17-0: Only camera and motors.
Configuration D17-0+w: Previous one + an additional WiFi card (Edimax).
Configuration D17-0+j: Previous one + joystick.
Configuration D17-1: LED lights and bumpers
What can each configuration do?
C0Jacopo
The trip begins with acquiring the parts. Here, we provide a link to all bits and pieces that are needed to build a Duckiebot, along with their price tag.
In general, keep in mind that:
Resources necessaries:
Results:
| Chassis | USD 20 |
| Camera with 160-FOV Fisheye Lens | USD 39 |
| Camera Mount | USD 8.50 |
| 300mm Camera Cable | USD 2 |
| Raspberry Pi 3 - Model B | USD 35 |
| Heat Sinks | USD 5 |
| Power supply | USD 7.50 |
| Class 10 MicroSD Card | USD 20 |
| Female/Female Jumper Wires (300mm) | USD 8 |
| Stepper Motor HAT - Mini Kit | USD 22.50 |
| GPIO Stacking Headers - DC motor hat headers 2x20 Stacking Extra Long | USD 2.50 |
| 16-Channel PWM/Servo HAT for Raspberry Pi - Mini Kit | USD 17.50 |
| Battery | USD 20 |
| 16 Nylon Standoffs (M2.5 12mm F 6mm M | USD 0.05/piece |
| 4 Nylon Hex Nuts (M2.5) | USD 0.02/piece |
| 4 Nylon Screws (M2.5x10) | USD 0.05/piece |
| Zip Ties 300x5mm | USD 8.99 |
| Joypad | USD 10.50 |
Premium Male/Male Jumper Wires (150mm) D17-1 |
USD 1.95 |
Wifi Augmenter D17-0+w |
USD 20 |
LEDs D17-1 |
USD 10 |
| GPIO Header - 40 pin female header | USD 1.50 |
LED HAT D17-1 |
USD |
| Bumpers | USD ?? |
| Total for minimum configuration | USD ?? |
| Total for fancy configuration | USD ?? |
We selected the Magician Chassis as the basic chassis for the robot (Figure 2).
We chose it because it has a double-decker configuration, and so we can put the battery in the lower part.
The chassis pack includes the motors and wheels as well as the structural part.
The price for this in the US is about USD 15-30.
The RPI-3 is the central computer of the Duckiebot. Duckiebot version D17 uses Model B (Figure 3) (A1.2GHz 64-bit quad-core ARMv8 CPU, 1GB RAM), a small but powerful computer.
The price for this in the US is about USD 35.
We want a hard-wired power source (5VDC, 2.4A, Micro USB) to supply the RPI-3 (Figure 4).
The price for this in the US is about USD 5-10.
The RPI-3 will heat up significantly during use. It is warmly recommended to add heat sinks, as in Figure 5. Since we will be stacking HATs on top of the RPI-3 with 15 mm standoffs, the maximum height of the heat sinks should be well below 15 mm. The chip dimensions are 15x15 mm and 10x10 mm.
The MicroSD card Figure 6is the hard disk of the RPI-3. 16 GigaBytes of capacity are sufficient.
The Camera is the main sensor of the Duckiebot. Version D17 equips a 5 Mega Pixels 1080p camera with wide field of view ($160^\circ$) fisheye lens (Figure 7).
The camera mount (Figure 8) serves to keep the camera looking forward at the right angle to the road (looking slightly down). The front cover is not essential.
A longer (300 mm) camera cable Figure 9 make assembling the Duckiebot easier, allowing for more freedom in the relative positioning of camera and computational stack.
The Edimax AC1200 EW-7822ULC wifi adpater Figure 10 improves the interactions with the Duckiebot by improving the connectivity between Duckiebot and laptop, especially useful in crowded environments (e.g., classroom).
The joypad is used to manually remote control the Duckiebot. Any 2.4 GHz wireless controller (with a tiny USB dongle) will do.
The model link in the table (Figure 11) does not include batteries (2 AA 1.5V)!
We use the DC+Stepper motor HAT to control the motors that drive the wheels.
use picture that shows only the hat without the motors
use picture without any accessories
The battery provides power to the Duckiebot.
We choose this (Figure 16) battery because it has a good combination of size (to fit in the lower deck of the Magician Chassis), high output amperage (2.4A and 2.1A at 5V DC) over two USB outputs, a good capacity (10400 mAh) at an affordable price (USD 20).
We use non electrically conductive standoffs (M2.5 12mm F 6mm M), nuts (M2.5), and screws (M2.5x10mm) to hold the RPI-3 to the chassis and the HATs stacked on top of the RPI-3.
In versions D17-0 and D17-0+w, the Duckiebot requires 12 standoffs, 4 nuts and 4 screws.
In version D17-1, the Duckiebot requires 16 standoffs, 4 nuts and 4 screws.
Two long (300x5 mm) zip ties are going to be useful to keep the battery at the lower deck from moving around.
In the fancy version D17-1, the Duckiebot is equipped with 5 RGB LEDs. LEDs can be used to signal to other Duckiebots, or just make cool patterns!
The pack of LEDs linked in the table above holds 10 LEDs, enough for two Duckiebots.
Daughterboard for Adafruit 16-Channel PWM / Servo HAT that enables connection with RGB LEDs, ADS1015 12 Bit, 4 Channel ADC, Monochrome 128x32 I2C OLED graphic display, and Adafruit 9-DOF IMU Breakout - L3GD20H + LSM303.
C0Shiying
Resources necessaries:
Results:
finish above
C0Shiying
Resources necessaries:
D17-C0 parts.The acquisition process is explained in Chapter 11.
Results:
D17-C0.Shiying: here will be the instruction about assembling the Duckiebot. :-)
Andrea
These are the instructions to reproduce the Ubuntu image that we use.
Please note that the image is already available, so you don’t need to do this manually.
However, this documentation might be useful if you would like to port the software to a different distribution.
Resources necessaries:
Results:
Download the image from the page
The file we are looking for is:
filename: ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
size: 1.2 GB
SHA256: dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2
After download, run the command sha256sum to make sure you have the right version:
laptop $ sha256sum ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2
If the string does not correspond exactly, your download was corrupted. Delete the file and try again.
Then decompress using the command xz:
laptop $ xz -d ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
Next, burn the image on to the SD card.
This procedure is explained in Section 74.4.
Remove the SD card and plug it in again in the laptop.
Ubuntu will mount two partitions, by the name of PI_ROOT and PI_BOOT.
Boot the disk in the Raspberry Pi.
Choose the following options:
language: English
username: ubuntu
password: ubuntu
hostname: duckiebot
Choose the option to log in automatically.
Reboot.
The WiFi was connected to airport network duckietown
with password quackquack.
Afterwards I upgraded all the software preinstalled with these commands:
duckiebot $ sudo apt update
duckiebot $ sudo apt dist-upgrade
Expect dist-upgrade to take quite a long time (up to 2 hours).
The Raspberry Pi is not accessible by SSH by default.
Run raspi-config:
duckiebot $ sudo raspi-config
choose “3. Interfacing Options”, and enable SSH,
We need to enable the camera and the I2C bus.
choose “3. Interfacing Options”, and enable camera, and I2C.
Also disable the graphical boot
Install these packages.
Etckeeper:
duckiebot $ sudo apt install etckeeper
Editors / shells:
duckiebot $ sudo apt install -y vim emacs byobu zsh
Git:
duckiebot $ sudo apt install -y git git-extras
Other:
duckiebot $ sudo apt install htop atop nethogs iftop
duckiebot $ sudo apt install aptitude apt-file
Development:
duckiebot $ sudo apt install -y build-essential libblas-dev liblapack-dev libatlas-base-dev gfortran libyaml-cpp-dev
Python:
duckiebot $ sudo apt install -y python-dev ipython python-sklearn python-smbus
duckiebot $ sudo pip install scipy --upgrade
I2C:
duckiebot $ sudo apt install -y i2c-tools
First, mark the kernel packages as not upgradeable:
$ sudo apt-mark hold raspberrypi-kernel raspberrypi-kernel-headers
raspberrypi-kernel set on hold.
raspberrypi-kernel-headers set on hold
Then, download and install the Edimax driver from this repository.
Install ROS.
The procedure is given in Section 83.1.
This is the old version.
There are two files that are important to edit.
The file /etc/network/interfaces should look like this:
# interfaces(5) file used by ifup(8) and ifdown(8)
# Include files from /etc/network/interfaces.d:
#source-directory /etc/network/interfaces.d
auto wlan0
# The loopback network interface
auto lo
iface lo inet loopback
# Wireless network interface
allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp
The file /etc/wpa_supplicant/wpa_supplicant.conf should look like this:
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="duckietown"
psk="quackquack"
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
auth_alg=OPEN
}
network={
key_mgmt=NONE
}
The files that describe the network configuration are in the directory
/etc/NetworkManager/system-connections/
This is the contents of the connection file duckietown, which
describes how to connect to the duckietown wireless network:
[connection]
id=duckietown
uuid=e9cef1bd-f6fb-4c5b-93cf-cca837ec35f2
type=wifi
permissions=
secondaries=
timestamp=1502254646
[wifi]
mac-address-blacklist=
mac-address-randomization=0
mode=infrastructure
ssid=duckietown
[wifi-security]
group=
key-mgmt=wpa-psk
pairwise=
proto=
psk=quackquack
[ipv4]
dns-search=
method=auto
[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=auto
This is the file
/etc/NetworkManager/system-connections/create-5ghz-network
Contents:
[connection]
id=create-5ghz-network
uuid=7331d1e7-2cdf-4047-b426-c170ecc16f51
type=wifi
# Put the Edimax interface name here:
interface-name=![wlx74da38c9caa0 - to change]
permissions=
secondaries=
timestamp=1502023843
[wifi]
band=a
# Put the Edimax MAC address here
mac-address=![74:DA:38:C9:CA:A0 - to change]
mac-address-blacklist=
mac-address-randomization=0
mode=ap
seen-bssids=
ssid=duckiebot-not-configured
[ipv4]
dns-search=
method=shared
[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=ignore
Note that there is an interface name and MAC address that need to be changed on each PI.
This enables the SSH server:
$ sudo systemctl enable ssh
Do the following:
Create an empty file using the dd (device-to-device copy) command:
duckiebot $ sudo dd if=/dev/zero of=/swap0 bs=1M count=512
This is for a 512 MB swap space.
Format the file for use as swap:
duckiebot $ sudo mkswap /swap0
Add the swap file to the system configuration:
duckiebot $ sudo vi /etc/fstab
Add this line to the bottom:
/swap0 swap swap
Activate the swap space:
duckiebot $ sudo swapon -a
First, make vi the default editor, using
$ sudo update-alternatives --config editor
and then choose vim.basic.
Then run:
$ sudo visudo
And then change this line:
%sudo ALL=(ALL:ALL) ALL
into this line:
%sudo ALL=(ALL:ALL) NOPASSWD:ALL
You should make the ubuntu user belong to the i2c and input groups:
duckiebot $ sudo adduser ubuntu i2c
duckiebot $ sudo adduser ubuntu input
: forgot to add to aug20 image:
duckiebot $ sudo adduser ubuntu video
You may need to do the following (but might be done already through raspi-config):
duckiebot $ sudo udevadm trigger
Do the basic SSH config.
The procedure is documented in Section 77.3.
this is not in the aug10 image.
Add .authorized_keys so that we can all do passwordless SSH.
The key is at the URL
https://www.dropbox.com/s/pxyou3qy1p8m4d0/duckietown_key1.pub?dl=1
Download to .ssh/authorized_keys:
duckiebot $ curl -o .ssh/authorized_keys ![URL above]
Add the following lines to ~ubuntu/.bashrc:
echo ""
echo "Welcome to a duckiebot!"
echo ""
echo "Reminders:"
echo ""
echo "1) Do not use the user 'ubuntu' for development - create your own user."
echo "2) Change the name of the robot from 'duckiebot' to something else."
echo ""
export EDITOR=vim
Andrea
Before you prepare the Duckiebot, you need to have a laptop with Ubuntu installed.
Requirements:
estimate time
Results:
Install Ubuntu 16.04.2.
For instructions, see for example this online tutorial.
On the choice of username: During the installation, create a user for yourself with a username different from ubuntu, which is the default. Otherwise, you may get confused later.
Use etckeeper to keep track of the configuration in /etc:
laptop $ sudo apt install etckeeper
Install ssh to login remotely and the server:
laptop $ sudo apt install ssh
Use byobu:
laptop $ sudo apt install byobu
Use vim:
laptop $ sudo apt install vim
Use htop to monitor CPU usage:
laptop $ sudo apt install htop
Additional utilities for git:
laptop $ sudo apt install git git-extras
Other utilities:
laptop $ sudo apt install avahi-utils ecryptfs-utils
Install ROS on your laptop.
The procedure is given in Section 83.1.
This is Flux for Linux. It is an accessibility/lab safety issue: bright screens damage eyes and perturb sleep [3].
Install redshift and run it.
laptop $ sudo apt install redshift-gtk
Set to “autostart” from the icon.
Optional but very encouraged: install the duckuments system. This will allow you to have a local copy of the documentation and easily submit questions and changes.
The procedure is documented in Section 6.4.
sudoSet up passwordless sudo.
This procedure is described in Section 14.11.
Do the basic SSH config.
The procedure is documented in Section 77.3.
![username]Next, create a private/public key pair for the user; call it ![username]@![robot name].
The procedure is documented in Section 77.5.
![username]‘s public key to GithubAdd the public key to your Github account.
The procedure is documented in Section 73.3.
If the step is done correctly, this command should succeed:
duckiebot $ ssh -T git@github.com
Set up Git locally.
The procedure is described in Section 79.3.
Andrea
Prerequisites:
D17-C0.This is the result of Chapter 13.
Result:
What does it mean “ready to use”?.
On the laptop, download the compressed image at this URL:
https://www.dropbox.com/s/1p4am7erdd9e53r/duckiebot-RPI3-AC-aug10.img.xz?dl=1
The size is 2.5 GB.
You can use:
$ curl -o duckiebot-RPI3-AC-aug10.img.xz ![URL above]
Uncompress the file:
$ xz -d -k duckiebot-RPI3-AC-aug10.img.xz
This will create a file of 32 GB in size.
To make sure that the image is downloaded correctly, compute its hash
using the program sha256sum:
$ sha256sum duckiebot-RPI3-AC-aug10.img
2ea79b0fc6353361063c89977417fc5e8fde70611e8afa5cbf2d3a166d57e8cf duckiebot-ac-aug10.img
Compare the hash that you obtain with the hash above. If they are different, there was some problem in downloading the image.
Next, burn the image on disk.
The procedure of how to burn an image is explained in Section 74.4.
Put the SD Card in the Duckiebot.
Turn on the Duckiebot by connecting the power cable to the battery.
Add figure
You can login to the Duckiebot in two ways:
duckietown WiFi network.In the worst case, you can use an HDMI monitor and a USB keyboard.
Connect the Duckiebot and your laptop to the same network switch.
Allow 30 s - 1 minute for the DHCP to work.
The Duckiebot connects automatically to a 2.4 GHz network
called “duckietown” and password “quackquack”.
Connect your laptop to the same wireless network.
To test that the Duckiebot is connected, try to ping it.
The hostname of a freshly-installed duckiebot is duckiebot-not-configured:
laptop $ ping duckiebot-not-configured.local
You should see output similar to the following:
PING duckiebot-not-configured.local (![X.X.X.X]): 56 data bytes
64 bytes from ![X.X.X.X]: icmp_seq=0 ttl=64 time=2.164 ms
64 bytes from ![X.X.X.X]: icmp_seq=1 ttl=64 time=2.303 ms
![...]
Next, try to log in using SSH, with account ubuntu:
laptop $ ssh ubuntu@duckiebot-not-configured.local
The password is ubuntu.
By default, the robot boots into Byobu.
Please see Section 80.1 for an introduction to Byobu.
Not sure it’s a good idea to boot into Byobu.
D17-0+w
The Duckiebot in configuration D17-C0+w can create a WiFi network.
It is a 5 GHz network; this means that you need to have a 5 GHz WiFi adapter in your laptop.
First, make sure that the Edimax is correctly installed.
Using iwconfig, you should see four interfaces:
duckiebot $ iwconfig
wlx![AABBCCDDEEFFGG] unassociated Nickname:"rtl8822bu"
![...]
lo no wireless extensions.
enxb827eb1f81a4 no wireless extensions.
wlan1 IEEE 802.11bgn ESSID:"duckietown"
![...]
Make note of the name wlx![AABBCCDDEEFFGG].
Look up the MAC address using the command:
duckiebot $ ifconfig wlx![AABBCCDDEEFFGG]
wlx74da38c9caa0 Link encap:Ethernet HWaddr ![AA:BB:CC:DD:EE:FF:GG]
Then, edit the connection file
/etc/NetworkManager/system-connections/create-5ghz-network
Make the following changes:
interface-name=![...], put “wlx![AABBCCDDEEFFGG]”.mac-address=![...], put “![AA:BB:CC:DD:EE:FF:GG]”.ssid=duckiebot-not-configured, put “ssid=![robot name]”.Reboot.
At this point you should see a new network being created named “![robot name]”.
You can connect with the laptop to that network.
If the Raspberry Pi’s network interface is connected to the duckietown network
and to the internet, the Raspberry Pi will act as a bridge to the internet.
This part should not be necessary anymore
The Duckiebot is configured by default to connect to a wireless network with
SSID duckietown. If that is not your SSID then you will need to change the
configuration.
You can add a new network by editing the file:
/etc/wpa_supplicant/wpa_supplicant.conf
You will see a block like the following:
network={
ssid="duckietown"
scan_ssid=1
psk="quackquack"
priority=10
}
Add a new one with your SSID and password.
This assumes you have a roughly similar wireless network setup - if not then you might need to change some of the other attributes.
Next, we need to update to bring the system up to date.
Use these commands
duckiebot $ sudo apt update
duckiebot $ sudo apt dist-upgrade
It is now time to give a name to the Duckiebot.
These are the criteria:
-”, “_”, etc.) .duckiebot”, “robot” or similar.From here on, we will refer to this string as “![robot name]”.
Every time you see ![robot name], you should substitute the name that you chose.
We will put the robot name in configuration files.
Files in /etc are only writable by root,
so you need to use sudo to edit them. For example:
duckiebot $ sudo vi ![filename]
Edit the file
/etc/hostname
and put “![robot name]” instead of duckiebot-not-configured.
Also edit the file
/etc/hosts
and put “![robot name]” where duckiebot-not-configured appears.
The first two lines of /etc/hosts should be:
127.0.0.1 localhost
127.0.1.1 ![robot name]
there is a command hostname that promises to change the hostname.
However, the change given by that command does not persist across reboots. You
need to edit the files above for the changes to persist.
Never add other hostnames in /etc/hosts. It is a tempting
fix when DNS does not work, but it will cause other problems
subsequently.
Then reboot the Raspberry Pi using the command
$ sudo reboot
After reboot, log in again, and run the command hostname to check that the
change has persisted:
$ hostname
![robot name]
You must not use the ubuntu user for development.
Instead, you need to create a new user.
Choose a user name, which we will refer to as ![username].
To create a new user:
duckiebot $ sudo useradd -m ![username]
Make the user an administrator by adding it to the group sudo:
duckiebot $ sudo adduser ![username] sudo
Make the user a member of the group input and i2c
duckiebot $ sudo adduser ![username] input
duckiebot $ sudo adduser ![username] video
duckiebot $ sudo adduser ![username] i2c
Set the shell bash:
duckiebot $ sudo chsh -s /bin/bash andrea
To set a password, use:
duckiebot $ sudo passwd ![username]
At this point, you should be able to login to the new user from the laptop using the password:
laptop $ ssh ![username]@![robot name]
Next, you should repeat some steps that we already described.
Do the basic SSH config.
The procedure is documented in Section 77.3.
![username]Next, create a private/public key pair for the user; call it ![username]@![robot name].
The procedure is documented in Section 77.5.
![username]‘s public key to GithubAdd the public key to your Github account.
The procedure is documented in Section 73.3.
If the step is done correctly, this command should succeed:
duckiebot $ ssh -T git@github.com
This procedure is in Section 79.3.
Make sure that you can login passwordlessly to your user from the laptop.
The procedure is explained in Section 77.6.
In this case, we have:
![local] = laptop, ![local-user] = your local user on the laptop,
![remote] = ![robot name], ![remote-user] = ![username].
If the step is done correctly, you should be able to login from the laptop to the robot, without typing a password:
laptop $ ssh ![username]@![robot name]
In general, if you find yourself:
ssh more than onceit means you should learn more about Linux and networks, and you are setting yourself up for failure.
Yes, you “can do without”, but with an additional 30 seconds of your time. The 30 seconds you are not saving every time are the difference between being productive roboticists and going crazy.
Really, it is impossible to do robotics when you have to think about IPs and passwords…
If you know what you are doing, you are welcome to install and use additional shells, but please keep Bash as be the default shell. This is important for ROS installation.
For the record, our favorite shell is ZSH with oh-my-zsh.
Check that the camera is connected using this command:
duckiebot $ vcgencmd get_camera
supported=1 detected=1
If you see detected=0, it means that the hardware connection is not working.
You can test the camera right away using a command-line utility
called raspistill.
Use the raspistill command to capture the file out.jpg:
duckiebot $ raspistill -t 1 -o out.jpg
Then download out.jpg to your computer using scp for inspection.
For instructions on how to use scp, see Subsection 77.8.1.
detected=0
If you see detected=0, it is likely that the camera is not connected correctly.
If you see an error that starts like this:
mmal: Cannot read camera info, keeping the defaults for OV5647
![...]
mmal: Camera is not detected. Please check carefully the camera module is installed correctly.
then, just like it says: “Please check carefully the camera module is installed correctly.”.
Andrea
Prerequisites:
The procedure is documented in Chapter 15.
The procedure is documented in Chapter 16.
The procedure is documented in Chapter 73.
Results:
Clone the repository in the directory ~/duckietown:
duckiebot $ git clone git@github.com:duckietown/Software.git ~/duckietown
For the above to succeed you should have a Github account already set up.
It should not ask for a password.
It asks for a password.
You missed some of the steps described in Chapter 73.
Other weird errors.
Probably the time is not set up correctly. Use ntpdate as above:
$ sudo ntpdate -u us.pool.ntp.org
All the following commands should be run in the ~/duckietown directory:
duckiebot $ cd ~/duckietown
Now we are ready to make the workspace. First you need to source the baseline ROS environment:
duckiebot $ source /opt/ros/kinetic/setup.bash
Then, build the workspace using:
duckiebot $ catkin_make -C catkin_ws/
For more information about catkin_make, see Subsection 83.5.3.
AC: I had to run it twice. The first time it complained:
In file included from /home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/src/apriltag_detector.cpp:1:0:
/home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/include/apriltags_ros/apriltag_detector.h:6:41: fatal error: duckietown_msgs/BoolStamped.h: No such file or directory
Automate this part
On the robot edit the file
~/duckietown/catkin_ws/src/duckietown/machines
You will see something like this:
<launch>
<arg name="env_script_path" default="~/duckietown/environment.sh"/>
<machine name="![robot name]" address="![robot name].local" user="![username]"
env-loader="$(arg env_script_path)"/>
...
...
</launch>
Now, duplicate a <machine> line between <launch> and </launch>, and replace the name and address string with the name of your vehicle.
For example, for Andrea, ![robot name] = emma and ![username] = andrea.
So, he would add this line:
<machine name="emma" address="emma.local" user="andrea" env-loader="$(arg env_script_path)"/>
Commit and push the new machines file. ( No, don’t commit the machines file.)
Plug the joystick receiver in one of the USB port on the Raspberry Pi.
To make sure that the joystick is detected, run:
duckiebot $ ls /dev/input/
and check if there is a device called js0 on the list.
Make sure that your user is in the group input and i2c:
duckiebot $ groups
![username] sudo input i2c
If input and i2c are not in the list, you missed a step. Ohi ohi!
You are not following the instructions carefully!
Consult again Section 16.11.
To test whether or not the joystick itself is working properly, run:
duckiebot $ jstest /dev/input/js0
Move the joysticks and push the buttons. You should see the data displayed change according to your actions.
SSH into the Raspberry Pi and run the following from the duckietown directory:
duckiebot $ cd ~/duckietown
duckiebot $ source environment.sh
The environment.sh setups the ROS environment at the terminal (so you can use
commands like rosrun and roslaunch).
Now make sure the motor shield is connected.
Run the command:
duckiebot $ roslaunch duckietown joystick.launch veh:=![robot name]
If there is no “red” output in the command line then pushing the left joystick knob controls throttle - right controls steering.
This is the expected result of the commands:
| left joystick up | forward |
| left joystick down | backward |
| right joystick left | turn left (positive yaw) |
| right joystick right | turn right (negative yaw) |
It is possible you will have to unplug and replug the joystick or just push lots of buttons on your joystick until it wakes up. Also make sure that the mode switch on the top of your joystick is set to “X”, not “D”.
Is all of the above valid with the new joystick?
Close the program using Ctrl-C.
The robot moves weirdly (e.g. forward instead of backward).
The cables are not correctly inserted. Please refer to the assembly guide for pictures of the correct connections. Try swapping cables until you obtain the expected behavior.
Check that the joystick has the switch set to the position “x”.And the mode light should be off.
The left joystick does not work.
If the green light on the right to the “mode” button is on, click the “mode” button to turn the light off. The “mode” button toggles between left joystick or the cross on the left.
The robot does not move at all.
The cables are disconnected.
The program assumes that the joystick is at /dev/input/js0.
In doubt, see Section 17.4.
Generally speaking, you can terminate any roslaunch command with Ctrl-C.
To completely shutdown the robot, issue the following command:
duckiebot $ sudo shutdown -h now
Then wait 30 seconds.
If you disconnect the power before shutting down properly using shutdown,
the system might get corrupted.
Then, disconnect the power cable, at the battery end.
If you disconnect frequently the cable at the Raspberry Pi’s end, you might damage the port.
Prerequisites:
The procedure is documented in Chapter 16.
roslaunch, topics, rostopic).put reference
Results:
It might be useful to do a quick camera hardware check.
The procedure is documented in Section 16.13.
On the laptop, create two Byobu windows.
A quick reference about Byobu commands is in Section 80.1.
You will use the two windows as follows:
You could also use multiple terminals instead of one terminal with multiple Byobu windows. However, using Byobu is the best practice to learn.
In the first window, we will launch the nodes that control the camera.
Activate ROS:
duckiebot $ source environment.sh
Run the launch file called camera.launch:
duckiebot $ roslaunch duckietown camera.launch veh:=![robot name]
At this point, you should see the red LED on the camera light up continuously.
In the terminal you should not see any red message, but only happy messages like the following:
![...]
[INFO] [1502539383.948237]: [/![robot name]/camera_node] Initialized.
[INFO] [1502539383.951123]: [/![robot name]/camera_node] Start capturing.
[INFO] [1502539384.040615]: [/![robot name]/camera_node] Published the first image.
For more information about roslaunch and “launch files”, see Section 83.3.
Switch to the second window.
Activate the ROS environment:
duckiebot $ source environment.sh
You can see a list of published topics with the command:
duckiebot $ rostopic list
For more information about rostopic, see Section 83.5.
You should see the following topics:
/![robot name]/camera_node/camera_info
/![robot name]/camera_node/image/compressed
/![robot name]/camera_node/image/raw
/rosout
/rosout_agg
You can use rostopic hz to see the statistics about the publishing frequency:
laptop $ rostopic hz /![robot name]/camera_node/image/compressed
On a Raspberry Pi 3, you should see a number close to 30 Hz:
average rate: 30.016
min: 0.026s max: 0.045s std dev: 0.00190s window: 841
You can view the messages in real time with the command rostopic echo:
laptop $ rostopic echo /![robot name]/camera_node/image/compressed
You should see a large sequence of numbers being printed to your terminal.
That’s the “image” — as seen by a machine.
If you are Neo, then this already makes sense. If you are not Neo, in
Chapter 20, you will learn how to visualize the image stream
on the laptop using rviz.
use Ctrl-C to stop rostopic.
Andrea
Prerequisites:
The procedure is documented in Chapter 17.
Results:
ROS nodes can be launched in two ways:
Which is better when is a long discussion that will be done later. Here we set up the “remote launch”.
draw diagrams
Software repository on the laptopAs you did on the Duckiebot, you should clone the Software
repository in the ~/duckietown directory.
The procedure is documented in Section 17.1.
Then, you should build the repository.
This procedure is documented in Section 17.2.
machines files on your laptopYou have to edit the machines files on your laptop, as you did on the
Duckiebot.
The procedure is documented in Section 17.3.
Now you are ready to launch the joystick demo remotely.
Make sure that you can login with SSH without a password. From the laptop, run:
laptop $ ssh ![username]@![robot name].local
If this doesn’t work, you missed some previous steps.
Run this on the laptop:
laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=![robot name]
You should be able to drive the vehicle with joystick just like the last example. Note that remotely launching nodes from your laptop doesn’t mean that the nodes are running on your laptop. They are still running on the Raspberry Pi in this case.
For more information about roslaunch, see Section 83.3.
rqt_consoleAlso, you might have notice that the terminal where you launch the launch file is not printing all the printouts like the previous example. This is one of the limitation of remote launch.
Don’t worry though, we can still see the printouts using rqt_console.
On the laptop, open a new terminal window, and run:
laptop $ export ROS_MASTER_URI=http://![robot name].local:11311/
laptop $ rqt_console
AC: I could not see any messages in rqt_console - not sure what is wrong.
You should see a nice interface listing all the printouts in real time, completed with filters that can help you find that message you are looking for in a sea of messages.
You can use Ctrl-C at the terminal where roslaunch was executed to stop all the
nodes launched by the launch file.
For more information about rqt_console, see Section 83.2.
roslaunch fails with an error similar to the following:
remote[![robot name].local-0]: failed to launch on ![robot name]:
Unable to establish ssh connection to [![username]@![robot name].local:22]:
Server u'![robot name].local' not found in known_hosts.
You have not followed the instructions that told you to add the HostKeyAlgorithms
option. Delete ~/.ssh/known_hosts and fix your configuration.
The procedure is documented in Section 77.3.
Andrea
Prerequisites:
The procedure is documented in Chapter 19.
The procedure is documented in Chapter 18.
You can find the Byobu tutorial in Section 80.1.
Results:
We are assuming that the joystick demo in Chapter 19 worked.
We are assuming that the procedure in Chapter 18 succeeded.
We also assume that you terminated all instances of roslaunch with Ctrl-C,
so that currently there is nothing running in any window.
On the laptop, this time create four Byobu windows.
A quick reference about Byobu commands is in Section 80.1.
You will use the four windows as follows:
rviz to see the camera image.Add figures
In the first window, launch the joystick remotely using the same procedure in Section 19.4.
laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=![robot name]
You should be able to drive the robot with the joystick at this point.
In the second window, we will launch the nodes that control the camera.
The launch file is called camera.launch:
laptop $ source environment.sh
laptop $ roslaunch duckietown camera.launch veh:=![robot name]
You should see the red led on the camera light up.
Open a third terminal on the laptop.
You can see a list of topics currently on the ROS_MASTER with the commands:
laptop $ source environment.sh
laptop $ export ROS_MASTER_URI=http://![robot name].local:11311/
laptop $ rostopic list
You should see the following:
/diagnostics
/![robot name]/camera_node/camera_info
/![robot name]/camera_node/image/compressed
/![robot name]/camera_node/image/raw
/![robot name]/joy
/![robot name]/wheels_driver_node/wheels_cmd
/rosout
/rosout_agg
rvizLaunch rviz by using these commands:
laptop $ source environment.sh
laptop $ source set_ros_master.sh ![robot name]
laptop $ rviz
For more information about rviz, see Section 83.4.
In the rviz interface, click “Add” on the lower left, then the “By topic”
tag, then select the “Image” topic by the name
/![robot name]/camera_node/image/compressed
Then click “ok”. You should be able to see a live stream of the image from the camera.
To stop the nodes: You can stop the node by pressing Ctrl-C on the terminal
where roslaunch was executed. In this case, you can use Ctrl-C in the
terminal where you launched the camera.launch.
You should see the red light on the camera turn off in a few seconds.
Note that the joystick.launch is still up and running, so you can still drive
the vehicle with the joystick.
Andrea
So far, we have been spelling out all commands for you, to make sure that you understand what is going on.
Now, we will tell you about some shortcuts that you can use to save some time.
in the future you will have to debug problems, and these problems might be harder to understand if you rely blindly on the shortcuts.
Results:
set_ros_master.shInstead of using:
$ export ROS_MASTER_URI=http://![robot name].local:11311/
You can use the “set_ros_master.sh” script in the repo:
$ source set_ros_master.sh ![robot name]
Note that you need to use source; without that, it will not work.
Instead of using
$ ssh ![username]@![robot name].local
You can set up SSH so that you can use:
$ ssh my-robot
To do this, create a host section in ~/.ssh/config with the following
contents:
Host my-robot
User ![username]
Hostname ![robot name].local
Here, you can choose any other string in place of “my-robot”.
Note that you cannot do
$ ping my-robot
You haven’t created another hostname, just an alias for SSH.
However, you can use the alias with all the tools that rely
on SSH, including rsync and scp.
Andrea
Andrea
Jacopo
Shiying
Liam?
D17-1 (LEDs) partsJacopo
D17-1 (LEDs) assemblyShiying
D17-1 (LEDs) setupAndrea
These are the theory chapters.
Jacopo
Jacopo
Liam?
Jacopo
Liam
Andrea
Matt
Andrea
Andrea
Jacopo
Jacopo
Jacopo
Matt
Matt
Matt
Matt
Matt
Liam
Liam
ETH
ETH
ETH
ETH
Jacopo
Jacopo
Jacopo
Nick and David
Nick and David
Nick and David
Jacopo
Nick and David
Nick
Liam
Liam
Liam
Liam
ETH
ETH
These are the exercises.
This part describes things that you should know about UNIX/Linux environments.
Please read the “background reading” section before you start, while the rest can be used as a reference.
Documentation writers: please make sure that every command used has a section in these chapters.
Andrea
This chapter describes how to create a Github account and setup SSH on the robot and on the laptop.
Our example account is the following:
Github name: greta-p
E-mail: greta-p@duckietown.com
Create a Github account (Figure 23).
Go to your inbox and verify the email.
Give the administrators your account name. They will invite you.
Accept the invitation to join the organization that you will find in your email.
You will do this procedure twice: once for the public key created on the laptop, and later with the public key created on the robot.
Requires:
This procedure is explained in Section 77.5.
Result:
Go to settings (Figure 24).
Add the public key that you created:
To check that all of this works, use the command
$ ssh -T git@github.com
The command tries to connect to Github using the private keys that you specified. This is the expected output:
Warning: Permanently added the RSA host key for IP address '![ip address]' to the list of known hosts.
Hi ![username]! You've successfully authenticated, but GitHub does not provide shell access.
If you don’t see the greeting, stop.
Repeat what you just did for the Duckiebot on the laptop as well, making sure to change the name of the file containing the private key.
Andrea
apt installto write
apt updateto write
apt dist-upgradehold back packages
pgrepto write
Test SD Card (or any disk) speed using the following commands,
which write to a file called ![filename].
$ dd if=/dev/zero of=![filename] bs=500K count=1024
$ sync
$ echo 3 | sudo tee /proc/sys/vm/drop_caches
$ dd if=![filename] of=/dev/null bs=500K count=1024
$ rm ![filename]
Note the sync and the echo command are very important.
Example results:
524288000 bytes (524 MB, 500 MiB) copied, 30.2087 s, 17.4 MB/s
524288000 bytes (524 MB, 500 MiB) copied, 23.3568 s, 22.4 MB/s
That is write 17.4 MB/s, read 22 MB/s.
htopYou can use htop to monitor CPU usage.
$ sudo apt install htop
iotop$ sudo apt install iotop
Requires:
Results:
First, find out what is the device name for the SD card.
Insert the SD Card in the slot.
Run the command:
$ sudo fdisk -l
Find your device name, by looking at the sizes.
For example, the output might contain:
Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
In this case, the device is /dev/mmcblk0. That will be the ![device]
in the next commands.
You may see /dev/mmcblk0pX or a couple of similar entries for each partition on the card,
where X is the partition number. If you don’t see anything like that, take out
the SD card and run the command again and see what disappeared.
Before proceeding, unmount all partitions.
Run df -h. If there are partitions like /dev/mmcblk0p![n], then unmount
each of them. For example:
laptop $ sudo umount /dev/mmcblk0p1
laptop $ sudo umount /dev/mmcblk0p2
Now that you know that the device is ![device],
you can burn the image to disk.
Let the image file be ![image file].
Burn the image using the command dd:
laptop $ sudo dd of=![device] if=![image file] status=progress bs=4M
Use the name of the device, without partitions. i.e., /dev/mmcblk0, not
/dev/mmcblk0pX.
Andrea
Preliminary reading:
Basics of networking, including
.local names work(ref to find).
to write
Make sure that you know:
ping: are you there?to write
ifconfigto write
$ ifconfig
iwlistWhat wireless networks do I have around?
$ sudo iwlist ![interface] scan | grep SSID
Does the interface support 5 GHz channels?
$ sudo iwlist ![interface] freq
Example output:
wlx74da38c9caa0 20 channels in total; available frequencies :
Channel 01 : 2.412 GHz
Channel 02 : 2.417 GHz
Channel 03 : 2.422 GHz
Channel 04 : 2.427 GHz
Channel 05 : 2.432 GHz
Channel 06 : 2.437 GHz
Channel 07 : 2.442 GHz
Channel 08 : 2.447 GHz
Channel 09 : 2.452 GHz
Channel 10 : 2.457 GHz
Channel 11 : 2.462 GHz
Channel 36 : 5.18 GHz
Channel 40 : 5.2 GHz
Channel 44 : 5.22 GHz
Channel 48 : 5.24 GHz
Channel 149 : 5.745 GHz
Channel 153 : 5.765 GHz
Channel 157 : 5.785 GHz
Channel 161 : 5.805 GHz
Channel 165 : 5.825 GHz
Current Frequency:2.437 GHz (Channel 6)
Note that in this example only some 5Ghz channels are supported (36, 40, 44, 48, 149, 153, 157, 161, 165); for example, channel 38, 42, 50 are not supported. This means that you need to set up the router not to use those channels.
Andrea
Andrea
to write
This installs the client:
$ sudo apt install ssh
This installs the server:
to write
This enables the server:
to write
The SSH configuration as a client is in the file
~/.ssh/config
Create the directory with the right permissions:
$ mkdir ~/.ssh
$ chmod 0700 ~/.ssh
Then add the following lines:
HostKeyAlgorithms ssh-rsa
The reason is that Paramiko, used by roslaunch,
does not support the ECSDA keys.
To log in to a remote computer ![remote] with user ![remote-user], use:
$ ssh ![remote-user]@![remote]
Symptom: “Offending key error”.
If you get something like this:
Warning: the ECDSA host key for ![...] differs from the key for the IP address '![...] '
Offending key for IP in /home/![user]/.ssh/known_hosts:![line]
then remove line ![line] in ~/.ssh/known_hosts.
This is a step that you will repeat twice: once on the Duckiebot, and once on your laptop.
The program will prompt you for the filename on which to save the file.
Use the convention
/home/![username]/.ssh/![username]@![host name]
/home/![username]/.ssh/![username]@![host name].pub
where:
![username] is the current user name that you are using (ubuntu or your chosen one);![host name] is the name of the host (the Duckiebot or laptop);An SSH key can be generated with the command:
$ ssh-keygen -h
The session output will look something like this:
Generating public/private rsa key pair.
Enter file in which to save the key (/home/![username]/.ssh/id_rsa):
At this point, tell it to choose this file:
/home/![username]/.ssh/![username]@![host name]
Then:
Enter passphrase (empty for no passphrase):
Press enter; you want an empty passphrase.
Enter same passphrase again:
Press enter.
Your identification has been saved in /home/![username]/.ssh/![username]@![host name]
Your public key has been saved in /home/![username]/.ssh/![username]@![host name].pub
The key fingerprint is:
![XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX] ![username]@![host name]
The key's randomart image is:
+--[ RSA 2048]----+
| . |
| o o . |
| o = o . o |
| B . . * o|
| S o O |
| o o . E|
| o o o |
| o + |
| .. . |
+-----------------+
Note that the program created two files.
The file that contains the private key is
/home/![username]/.ssh/![username]@![host name]
The file that contains the public key has extension .pub:
/home/![username]/.ssh/![username]@![host name].pub
Next, tell SSH that you want to use this key.
Make sure that the file ~/.ssh/config exists:
$ touch ~/.ssh/config
Add a line containing
IdentityFile ![PRIVATE_KEY_FILE]
(using the filename for the private key).
Check that the config file is correct:
$ cat ~/.ssh/config
![...]
IdentityFile ![PRIVATE_KEY_FILE]
![...]
Assumptions:
![local]” and “![remote]”,
with users “![local-user]” and “![remote-user]”.![local-user] on ![local].This procedure is described in Section 77.5.
Results:
![local] computer, ![local-user] will be able to log in to
![remote] computer without a password.First, connect the two computers to the same network, and make sure that you
can ping ![remote] from ![local]:
![local] $ ping ![remote].local
Do not continue if you cannot do this successfully.
If you have created a keypair for ![local-user], you will have a public key
in this file on the ![local] computer:
/home/![local-user]/.ssh/![local-user]@![local].pub
This file is in the form:
ssh-rsa ![long list of letters and numbers] ![local-user]@![local]
You will have to copy the contents of this file on the ![remote] computer,
to tell it that this key is authorized.
On the ![remote] computer, edit or create the file:
/home/![remote-user]/.ssh/authorized_keys
and add the entire line as above containing the public key.
Now, from the ![local] computer, try to log in into the ![remote] one:
![local] $ ssh ![remote-user]@![remote]
This should succeed, and you should not be asked for a password.
Sometimes, SSH does not work because you have the wrong permissions on some files.
In doubt, these lines fix the permissions for your .ssh directory.
$ chmod 0700 ~/.ssh
$ chmod 0700 ~/.ssh/*
to write
to write
Andrea
To do quick changes to files, especially when logged remotely, we suggest you use the VI editor, or more precisely, VIM (“VI iMproved”).
Install like this:
$ sudo apt install vim
Suggested ~/.vimrc:
syntax on
set number
filetype plugin indent on
highlight Comment ctermfg=Gray
autocmd FileType python set complete isk+=.,(
to write
Use the > command to indent.
To indent 5 lines, use 5 > >.
To mark a block of lines and indent it, use V.
For example, use VJJ> to indent 3 lines.
Use < to dedent.
to write
to write
Andrea
to write
The basic Git program is installed using
$ sudo apt install git
Additional utilities for git are installed using:
$ sudo apt install git-extras
This include the git-ignore utility.
This should be done twice, once on the laptop, and later, on the robot.
These options tell Git who you are:
$ git config --global user.email "![email]"
$ git config --global user.name "![full name]"
Also do this, and it doesn’t matter if you don’t know what it is:
$ git config --global push.default simple
You can clone without history with the command:
$ git clone --depth 1 ![repository URL]
The symptom is:
$ git push
Username for 'https://github.com':
Diagnosis: the remote is not correct.
If you do git remote you get entries with https::
$ git remote -v
origin https://github.com/duckietown/Software.git (fetch)
origin https://github.com/duckietown/Software.git (push)
Expectation:
$ git remote -v
origin git@github.com:duckietown/Software.git (fetch)
origin git@github.com:duckietown/Software.git (push)
Solution:
$ git remote remove origin
$ git remote add origin git@github.com:duckietown/Software.git
git push complains about upstreamThe symptom is:
fatal: The current branch ![branch name] has no upstream branch.
Solution:
$ git push --set-upstream origin ![branch name]
Andrea
You need to learn to use Byobu. It will save you much time later.
See the screencast on the website http://byobu.co/.
To write
On Ubuntu, install using:
$ sudo apt install byobu
You can change the escape sequence from Ctrl-A to something else by using the configuration tool that appears when you type F9.
Commands to use windows:
| Using function keys | Using escape sequences | |
| Create new window | F2 | Ctrl-A then C |
| Previous window | F3 | |
| Next window | F4 | |
| Switch to window | Ctrl-A then a number | |
| Close window | F6 | |
| Rename window | Ctrl-A then , |
Commands to use panes (windows split in two or more):
| Using function keys | Using escape sequences | |
| Split horizontally | Shift-F2 | Ctrl-A then | |
| Split vertically | Ctrl-F2 | Ctrl-A then % |
| Switch focus among panes | Ctrl-↑↓←→ | Ctrl-A then one of ↑↓←→ |
| Break pane | Ctrl-A then ! |
Other commands:
| Using function keys | Using escape sequences | |
| Help | Ctrl-A then ? | |
| Detach | Ctrl-A then D |
Scroll up and down using fnoption↑ and fnoption↓.
Highlight using alt
GNU Screen is fine as well.
Andrea
To write
This part is about how to develop software for the Duckiebot.
Install using:
$ sudo apt install virtualenv
matplotlib
seaborne
numpy
panda
scipy
opencv
...
Liam
This part installs ROS. You will run this twice, once on the laptop, once on the robot.
The first commands are copied from this page.
Tell Ubuntu where to find ROS:
$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
Tell Ubuntu that you trust the ROS people (they are nice folks):
$ sudo apt-key adv --keyserver hkp://ha.pool.sks-keyservers.net:80 --recv-key 421C365BD9FF1F717815A3895523BAEEB01FA116
Fetch the ROS repo:
$ sudo apt update
Now install the mega-package ros-kinetic-desktop-full.
$ sudo apt install ros-kinetic-desktop-full
There’s more to install:
$ sudo apt install ros-kinetic-{tf-conversions,cv-bridge,image-transport,camera-info-manager,theora-image-transport,joy,image-proc,compressed-image-transport,phidgets-drivers,imu-complementary-filter,imu-filter-madgwick}
Do not install packages by the name of ros-X, only those by
the name of ros-kinetic-X. The packages ros-X are from another version of ROS.
: not done in aug20 image:
Initialize ROS:
$ sudo rosdep init
$ rosdep update
rqt_consoleto write
roslaunchto write
rvizto write
rostopicto write
rostopic hzto write
rostopic echoto write
catkin_maketo write
![computer] is not in your SSH known_hosts file
See this thread. Remove the known_hosts file and make sure you
have followed the instructions in Section 77.3.
what-the-duck is a program that tests dozens of configuration
inconsistencies that can happen on a Duckiebot.
To use it, first compile the repository, and then run:
$ ./what-the-duck
what-the-duckThe idea is to add to what-the-duck all the tests that can be automated.
The documentation about to do that is not ready yet.
The current tests are available in the file:
./catkin_ws/src/f23-LED/led_detection/include/what_the_duck/list_of_checks.py
Here’s the list of tests already added:
✓ Camera is detected
✓ Scipy is installed
✓ sklearn is installed
✓ Date is set correctly
✓ Not running as root
✓ Not running as ubuntu
✓ Member of group sudo
✓ Member of group input
✓ Member of group video
✓ Member of group i2c
✓ ~/.ssh exists
✓ ~/.ssh permissions
✓ ~/.ssh/config exists
✓ SSH option HostKeyAlgorithms is set
✓ At least one key is configured.
✓ ~/.ssh/authorized_keys exists
✓ Git configured
✓ Git email set
✓ Git name set
✓ Git push policy set
✓ Edimax detected
✓ The hostname is configured
✓ /etc/hosts is sane
✓ Correct kernel version
✓ Messages are compiled
✓ Shell is bash
✓ Working internet connection
✓ Github configured
✓ Joystick detected
✓ Environment variable DUCKIETOWN_ROOT
✓ ${DUCKIETOWN_ROOT} exists
✓ Wifi network configured
Please add below any configuration test that can be automated:
Check that all the rosX command
resolve to a file/opt/ros/kinetic/bin/rosX.
Make sure that packages such as python-roslaunch
are not installed. (The user is invited to install it when roslaunch is not found!)
Repository remote is not https.
Editor is set to vim.
They put the right MAC address in the network configuration
☐ The name of the package is package_![handle]
☐ The directory is in …
☐ The messages are called ….
☐ there is a readme file
☐ there is the first launch file
This is the first time that a class is taught jointly across 3 continents!
There are 4 universities involved in the joint teaching for the term:
This part of the Duckiebook describes all the information that is needed by the students of the four institutions.
Andrea
The first rule of Duckietown
The first rule of Duckietown is: you don’t talk about Duckietown, using email.
Instead, we use a communication platform called Slack.
There is one exception: inquiries about “meta” level issues, such as course enrollment and other official bureaucratic issues can be communicated via email.
The second rule of Duckietown
The second rule of Duckietown is: be kind and respectful, and have fun.
The third rule of Duckietown
The third rule of Duckietown is: read the instructions carefully.
Do not blindly copy and paste.
Only run a command if you know what it does.
At ETHZ, UdeM, TTIC, the class will be more-or-less synchronized. The materials are the same; there is some slight variation in the ordering.
Moreover, there will be some common groups for the projects.
The NCTU class is undergraduate level. Students will learn slightly simplified materials. They will not collaborate directly with the classes.
To participate in Duckietown, students must use two accounts: Slack and Github.
You need a Slack account, for team discussion and organization.
Sign up link here:
Account naming convention
Account naming convention
A Github account;
Membership in the Duckietown organization.
As an instructor/TA for the Fall 2017 class, in addition to the accounts above, these are two more accounts that you need.
Twist is used for class organization (such as TAs, logistics);
TODO:
Google Docs is used to maintain TODOs and other coordination materials.
how to be authorized?
In particular:
Andrea
This section describes information specific for ETH Zürich students.
to write
All really important information, such as deadlines, is in the authoritative website:
to write
To write
to write
Liam
to write
Matt
to write
Nick
to write
ubuntu userOn each Duckiebot it is possible to log in as the ubuntu user using
a common key.
Now, let’s set up passwordless SSH, so that you don’t need to type a password.
On the laptop, create the .ssh directory:
laptop $ mkdir -p ~/.ssh
The key duckietown_key1 is found at the URL:
https://www.dropbox.com/s/q23qptu01u7ur3y/duckietown_key1?dl=1
Download the file and call it ~/.ssh/duckietown_key1
laptop $ curl -o ~/.ssh/duckietown_key1 ![URL above]
Edit the permission of the file. SSH wants the key file to be not readable or writable from other users or groups.
laptop $ chmod 600 ~/.ssh/duckietown_key1
Regenerate the public key according to:
laptop $ ssh-keygen -f ~/.ssh/duckietown_key1 -y > ~/.ssh/duckietown_key1.pub
On the laptop, now edit ~/.ssh/config and add the following lines:
Host ![robot name]
Hostname ![robot name].local
User ![user name]
IdentityFile ~/.ssh/duckietown_key1
HostKeyAlgorithms ssh-rsa
Now you should be able to connect without using a password.
The following command should connect without a password being asked:
laptop $ ssh ubuntu@![robot name]
“Scheme missing”
If there are issues such as “scheme missing” and the file
duckietown_key1 does not exist in the ~/.ssh/ folder, but instead
downloaded a file named duckietown_key1?dl=1 in the current folder, simply
rename duckietown_key1?dl=1 to duckietown_key1 and copy it over to the
directory ~/.ssh/.